home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / Wimp / Menus < prev    next >
Encoding:
Text File  |  1988-12-06  |  4.6 KB  |  113 lines
  1. > Wimp.Menus
  2.  
  3. New Calls
  4. ---------
  5.  
  6.         Wimp_CreateMenu
  7.         Wimp_CreateSubMenu
  8.         Wimp_Poll:  reason code 9  (Menu_Selection)
  9.         Wimp_Poll:  reason code 17 (Menu_Warning message)
  10.  
  11.  
  12. Overview
  13. --------
  14.  
  15. The user interface to menus is as follows:
  16.  
  17.   MENU button click in window ==> open menu tree appropriate to that window
  18.   moving over right-arrow icons in a menu causes the submenu to be opened
  19.   MENU or SELECT button click on an item selects it and closes the menu tree
  20.   ADJUST button click on an item selects it and keeps the menu tree open
  21.   menus with a title bar can be picked up and moved around
  22.   any button click outside the menu tree cancels the menus
  23.   icons can be ticked to show current settings
  24.   shaded icons cannot be selected, and their submenus cannot be opened
  25.  
  26. The significant change to this interface since Arthur 1.20 is that a menu
  27. selection can be made with the ADJUST button so that the menu tree remains
  28. open.
  29.  
  30. A facility has also been added so that an application can be notified when a
  31. particular branch of the menu tree is being activated, and can take
  32. appropriate action.  This allows, for example, a particular menu to display
  33. different 'tick' information depending on which part of the tree it has been
  34. activated from.
  35.  
  36.  
  37. Persistent Menus
  38. ----------------
  39.  
  40. To retain backwards compatibility with the old Wimp, the following approach
  41. has been taken to the problem of keeping the menu tree open after a selection
  42. has been made using the ADJUST button:
  43.  
  44.      *  When a menu selection happens, the Wimp does not close the menu tree
  45.         immediately, but simply sets an internal flag.  It then returns a
  46.         menu_select reason code from Wimp_Poll, as before.
  47.  
  48.      *  When the application receives the Menu_Select reason code, it should
  49.         perform the appropriate actions, as normal.  After that, it should
  50.         make a call to Wimp_GetPointerInfo to find out the state of the mouse
  51.         buttons.  If the right-hand button is depressed (bit 1 of the button
  52.         state), it should re-encode its menu tree (depending on what happened
  53.         as a result of the menu selection), and call Wimp_CreateMenu with the
  54.         same menu tree pointer.  It should then return to its polling loop.
  55.  
  56.      *  When Wimp_Poll is called, if the current menu tree has been marked
  57.         temporary, and Wimp_CreateMenu has not subsequently been called, the
  58.         tree is closed.
  59.  
  60.      *  When Wimp_CreateMenu is called, the Wimp checks to see if this tree
  61.         corresponds to the one currently active.  If it does correspond, it
  62.         attempts to open the tree in the same way it is already, keeping the
  63.         coordinates the same, and selecting the same submenus.  This process
  64.         continues as far as possible, until the end of the tree is reached,
  65.         the tree fails to correspond to the old one, or an item has become
  66.         shaded.
  67.  
  68. On old Wimps, only the first menu in the tree will be re-opened.
  69.  
  70.  
  71. Menu warning message
  72. --------------------
  73.  
  74. To ask the Wimp to give a warning message when a particular branch of the
  75. menu tree is accessed, the application program should:
  76.  
  77.      *  set bit 3 of the menu flags of the entry containing the submenu pointer
  78.  
  79.      *  when the mouse pointer is placed over the right-arrow icon of this
  80.         entry, instead of simply opening the submenu, the Wimp will return a
  81.         message of the following form from Wimp_Poll:
  82.  
  83.             R0 = 17
  84.             R1 --> block (as passed in to Wimp_Poll)
  85.               +0 = size of block
  86.               +4 = 0 (message from Wimp)
  87.               +8 = message reference number
  88.              +12 = 0
  89.              +16 = &400C0  (menu warning)
  90.              +20 = submenu pointer
  91.              +24 = x-coordinate of proposed submenu
  92.              +28 = y-coordinate of proposed submenu
  93.              +32.. = menu tree so far (selection numbers)
  94.                      terminated by -1
  95.  
  96.      *  on receipt of this message, the application should perform whatever
  97.         processing it wants to, and then open the submenu as follows:
  98.  
  99.             Wimp_CreateSubMenu
  100.             Entry:  R1 --> submenu
  101.                     R2 = x-coordinate of menu
  102.                     R3 = y-coordinate of menu
  103.  
  104.         (R1,R2 and R3 are taken from the message block (+20,24,28).
  105.  
  106. Note that the submenu pointer itself does not have to be set up when the main
  107. menu is created - it could just be a dummy pointer, and the call to
  108. Wimp_CreateSubMenu could substitute in the correct menu tree as appropriate. 
  109. This allows, for example, for a series of dialogue menus to be accessible via
  110. the menu tree - the appropriate window is created when it is required, and
  111. the window handle is passed in to Wimp_CreateSubMenu.
  112.  
  113.